authselect(8)
=============
:revdate: 2018-03-18

NAME
----

authselect - select system identity and authentication sources.

SYNOPSIS
--------
 authselect [--debug] [--trace] [--warn] command [command options]

DESCRIPTION
-----------
*Authselect* is a tool to configure system identity and authentication sources
and providers by selecting a specific profile. Profile is a set of files that
describes how the resulting system configuration will look like. When a profile
is selected, *authselect* will create nsswitch.conf(5) and PAM(8) stack to use
identity and authentication sources defined by the profile.

If the provided profile set is not sufficient, the administrator may create
a custom profile by putting it in a special profile directory
({AUTHSELECT_CUSTOM_DIR}). By doing so, the profile is immediately
usable by *authselect*. See _authselect-profiles(5)_ for more information
on extending existing profiles.

OPT-IN TO AUTHSELECT
--------------------
Authselect will not touch your existing configuration unless it has already
been created by it. If you want to start using authselect to configure your
system authentication, please call *authselect select* with *--force* parameter
first (e.g. *authselect select sssd --force*). The *--force* parameter tells
authselect that it is all right to overwrite existing non-authselect
configuration (see description below). Using the *--force* parameter will
automatically generate a backup of your current configuration so if you wish
to go back you can restore it with *authselect backup-restore* command
(see description below).

OPT-OUT FROM AUTHSELECT
-----------------------
To stop authselect from managing your configuration, run *authselect opt-out*.
This will remove all authselect configuration from your system and you can then
modify your configuration manually.

AVAILABLE COMMANDS
------------------
To list all available commands run *authselect* without any parameters.
To print help for the selected command run *authselect COMMAND --help*.

*select* profile_id [features] [-f, --force] [-q, --quiet] [-b] [--backup=NAME]::
    Activate desired profile. See profile description with *show* command,
    to list profile specific optional features.

    *--force, -f*:::
        Write changes even if the previous configuration was not created by
        authselect but by other tool or by manual changes. This option will
        automatically backup system files before writing any change unless
        *--nobackup* option is set.

    *-b*:::
        Backup system files before activating the selected profile. The backup
        will be stored at {AUTHSELECT_BACKUP_DIR}/NAME. Current time with
        unique string is used as a name of the backup. This is a shortcut
        for *--backup=*.

    *--backup=NAME*:::
        Backup system files before activating the selected profile. The backup
        will be stored at {AUTHSELECT_BACKUP_DIR}/NAME. Current time with
        unique string is used as a name if no value is provided.

    *--nobackup*:::
        Do not backup system configuration even if *--force* is set.

    *--quiet, -q*:::
        The command will not print any informational message such as additional
        profile requirements or backup location. Errors are still being print.

*apply-changes* [-b] [--backup=NAME]::
    Re-apply currently selected profile. If the profile templates were updated
    this command can be used to regenerate current system configuration in
    order to apply these changes on the system. This command will only re-apply
    the changes if the existing configuration is a valid authselect
    configuration, otherwise an error is returned.

    *-b*:::
        Backup system files before applying changes. The backup
        will be stored at {AUTHSELECT_BACKUP_DIR}/NAME. Current time with
        unique string is used as a name of the backup. This is a shortcut
        for *--backup=*.

    *--backup=NAME*:::
        Backup system files before applying changes. The backup will
        be stored at {AUTHSELECT_BACKUP_DIR}/NAME. Current time with unique
        string is used as a name if no value is provided.

*list*::
    List available profiles.

*list-features* profile_id::
    List all features available in given profile. +
    _Note:_ This will only list the features without any description. Please,
    read the profile documentation with *show* to see what the features do.

*show* profile_id::
    Print information about the profile.

*requirements* profile_id [features]::
    Print information about profile requirements.

*current* [-r, --raw]::
    Print information about currently selected profiles. If *--raw* option
    is specified, the command will print raw parameters as they were passed
    to *select* command instead of formatted output.

*check*::
    Check if the current configuration is valid (it was either created by
    *authselect* or there are no leftovers from previous authselect
    configuration).

*test* profile_id [options] [features]::
    Print content of files generated by *authselect* without actually writing
    anything to system configuration.

    *-a, --all*:::
        Print content of all files.

    *-n, --nsswitch*:::
        Print nsswitch.conf content.

    *-s, --system-auth*:::
        Print system-auth content.

    *-p, --password-auth*:::
        Print password-auth content.

    *-c, --smartcard-auth*:::
        Print smartcard-auth content.

    *-f, --fingerprint-auth*:::
        Print fingerprint-auth content.

    *-o, --postlogin*:::
        Print postlogin content.

    *-d, --dconf-db*:::
        Print dconf database content.

    *-l, --dconf-lock*:::
        Print dconf lock content.

*enable-feature* feature [-b] [--backup=NAME] [-q, --quiet]::
    Enable feature in the currently selected profile.

    *-b*:::
        Backup system files before enabling feature. The backup
        will be stored at {AUTHSELECT_BACKUP_DIR}/NAME. Current time with
        unique string is used as a name of the backup. This is a shortcut
        for *--backup=*.

    *--backup=NAME*:::
        Backup system files before enabling feature. The backup will
        be stored at {AUTHSELECT_BACKUP_DIR}/NAME. Current time with unique
        string is used as a name if no value is provided.

    *--quiet, -q*:::
        The command will not print any informational message such as additional
        profile requirements or backup location. Errors are still being print.

*disable-feature* feature [-b] [--backup=NAME]::
    Disable feature in the currently selected profile.

    *-b*:::
        Backup system files before disabling feature. The backup
        will be stored at {AUTHSELECT_BACKUP_DIR}/NAME. Current time with
        unique string is used as a name of the backup. This is a shortcut
        for *--backup=*.

    *--backup=NAME*:::
        Backup system files before disabling feature. The backup will
        be stored at {AUTHSELECT_BACKUP_DIR}/NAME. Current time with unique
        string is used as a name if no value is provided.

*create-profile* NAME [--vendor,-v] [options]::
    Create a new custom profile named _NAME_. The profile can be based on an
    existing profile in which case the new profile templates are either copied
    from the base profile or symbolic links to these files are created if
    such option is selected.

    *--vendor,-v*:::
        The new profile is a vendor profile instead of a custom profile. See
        _authselect-profiles(5)_ for more information on profile types.

    *--base-on=BASE-ID, -b=BASE-ID*:::
        The new profile will be based on a profile named _BASE-ID_. The base
        profile location is determined with these steps:
        . If _BASE-ID_ starts with prefix _custom/_ it is a custom profile.
        . Try if _BASE-ID_ is found in vendor profiles.
        . Try if _BASE-ID_ is found in default profiles.
        . Return an error.

    *--base-on-default*:::
        The base profile is a default profile even if it is found also within
        vendor profiles.

    *--symlink-meta*:::
        Meta files, such as _README_ and _REQUIREMENTS_ will be symbolic links
        to the origin profile files instead of their copy.

    *--symlink-nsswitch*:::
        _nsswitch.conf_ template will be symbolic link to the origin profile
        file instead of its copy.

    *--symlink-pam*:::
        _PAM_ templates will be symbolic links to the origin profile files
        instead of their copy.

    *--symlink-dconf*:::
        _dconf_ templates will be symbolic links to the origin profile files
        instead of their copy.

    *--symlink=FILE,-s=FILE*:::
        Create a symbolic link for a template file _FILE_ instead of creating
        its copy. This option can be passed multiple times.

BACKUP COMMANDS
---------------
These commands can be used to manage backed up configurations.

*backup-list* [-r, --raw]::
    Print available backups.  If *--raw* option is specified, the command will
    print only backup names without any formatting and additional information.

*backup-remove* BACKUP::
    Permanently delete backup named _BACKUP_.

*backup-restore* BACKUP::
    Restore configuration from backup named _BACKUP_. *Note:* this will
    overwrite current configuration.

OTHER COMMANDS
--------------

*opt-out*::
    Remove authselect configuration. This will restore nsswitch and PAM
    configuration under its system location and authselect will no longer
    manage it. Run *authselect select* to opt-in again.

COMMON OPTIONS
--------------
These options are available with all commands.

*--debug*::
    Print debugging information and error messages.

*--trace*::
    Print information about what the tool is doing.

*--warn*::
    Print information about unexpected situations that do not affect
    the program execution but may indicate some undesired situations
    (e.g. unexpected file in a profile directory).

ifeval::[{BUILD_USER_NSSWITCH} == 1]
NSSWITCH.CONF MANAGEMENT
------------------------
Authselect generates {AUTHSELECT_NSSWITCH_CONF} and does not allow any user
changes to this file. Such changes are detected and authselect will refuse to
write any system configuration unless a *--force* option is provided to
the *select* command. This mechanism prevents authselect from overwriting
anything that does not match any available profile.

Any user changes to nsswitch maps must be done in file
{AUTHSELECT_CONFIG_DIR}/user-nsswitch.conf. When authselect generates
new _nsswitch.conf_ it reads this file and combines it with configuration
from selected profile. The profile configuration takes always precedence.
In other words, profiles do not have to set all nsswitch maps but can set only
those that are relevant to the profile. If a map is set within a profile,
it always overwrites the same map from _user-nsswitch.conf_.

.Example 1
[subs="attributes"]
----
# "sssd" profile
$ cat {AUTHSELECT_PROFILE_DIR}/sssd/nsswitch.conf
passwd:     sss files systemd
group:      sss files systemd
netgroup:   sss files
automount:  sss files
services:   sss files
sudoers:    files sss {include if "with-sudo"}

$ cat {AUTHSELECT_CONFIG_DIR}/user-nsswitch.conf
passwd: files sss
group: files sss
hosts: files dns myhostname
sudoers: files

$ authselect select sssd

# passwd and group maps from user-nsswitch.conf are ignored
$ cat {AUTHSELECT_NSSWITCH_CONF}
passwd:     sss files systemd
group:      sss files systemd
netgroup:   sss files
automount:  sss files
services:   sss files
hosts:      files dns myhostname
sudoers:    files

$ authselect select sssd with-sudo

# passwd, group and sudoers maps from user-nsswitch.conf are ignored
$ cat {AUTHSELECT_NSSWITCH_CONF}
passwd:     sss files systemd
group:      sss files systemd
netgroup:   sss files
automount:  sss files
services:   sss files
sudoers:    files sss
hosts:      files dns myhostname
----
endif::[]

TROUBLESHOOTING
---------------

How can I tell if my system is using authselect?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use *authselect check*. The output will tell you if you have 1) configuration
generated by authselect 2) non-authselect configuration or 3) configuration
that was generated by authselect but modified manually at some point.

Is nsswitch.conf supposed to be a symbolic link now?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Authselect generates your system configuration from scratch and stores it
at {AUTHSELECT_CONFIG_DIR}. System files are then created as symbolic links
to this directory. Symbolic links are used to make it clear that authselect
is now owning your configuration and should be used instead of any manual
modification.

Error: Unexpected changes to the configuration were detected.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For example:
....
[error] [/etc/authselect/nsswitch.conf] does not exist!
[error] [/etc/nsswitch.conf] is not a symbolic link!
[error] [/etc/nsswitch.conf] was not created by authselect!
[error] Unexpected changes to the configuration were detected.
[error] Refusing to activate profile unless those changes are removed or overwrite is requested.
....
This means that your configuration is unknown to authselect and as such it
will not be modified. To fix this, please call *authselect select* with
*--force* parameter to say that it is all right to overwrite it.

RETURN CODES
------------
The *authselect* can return these exit codes:

* 0: Success.
* 1: Generic error.
* 2: Profile or configuration was not found or the system was not configured with authselect.
* 3: Current configuration is not valid, it was edited without authselect.
* 4: System configuration must be overwritten to activate an authselect profile, --force parameter is needed.
* 5: Executed command must be run as root.
* 6: No configuration was detected.

GENERATED FILES
---------------
Authselect creates and maintains the following files to configure system
identity and authentication providers properly.

*{AUTHSELECT_NSSWITCH_CONF}*::
    Name Service Switch configuration file.

*{AUTHSELECT_PAM_DIR}/system-auth*::
    PAM stack that is included from nearly all individual service configuration
    files.

*{AUTHSELECT_PAM_DIR}/password-auth, smartcard-auth, fingerprint-auth*::
    These PAM stacks are for applications which handle authentication from
    different types of devices via simultaneously running individual
    conversations instead of one aggregate conversation.

*{AUTHSELECT_PAM_DIR}/postlogin*::
     The  purpose  of  this  PAM stack is to provide a common place for all
     PAM modules which should be called after the stack configured in
     system-auth or the other common PAM configuration files. It is included
     from all individual service configuration files that provide login service
     with shell or file access. _NOTE: the modules in the postlogin
     configuration file are executed regardless of the success or failure of
     the modules in the system-auth configuration file._

*{AUTHSELECT_DCONF_DIR}/{AUTHSELECT_DCONF_FILE}*::
    Changes to dconf database. The main uses case of this file is to set
    changes for gnome login screen in order to enable or disable smartcard
    and fingerprint authentication.

*{AUTHSELECT_DCONF_DIR}/locks/{AUTHSELECT_DCONF_FILE}*::
    This file define locks on values set in dconf database.

SEE ALSO
--------
authselect-profiles(5), authselect-migration(7), nsswitch.conf(5), PAM(8)
